Kanzi  3.9.7
Kanzi Engine API
kanzi::Application Class Reference

Application class is the base class for Kanzi applications. More...

#include <kanzi/core.ui/application/application.hpp>

Inheritance diagram for kanzi::Application:
[legend]

Public Member Functions

 Application ()
 Constructs the application object. More...
 
Vector2 getRenderingAreaOffset () const
 Returns the translation that Kanzi uses as the arrange transformation of the default Screen node. More...
 
TextureSharedPtr getRootCompositionTarget () const
 Returns the root composition target of the application. More...
 
StartupProfilerRegistrygetStartupProfilerRegistry () const
 Gets the startup profiler registry. More...
 
void initialize (const SystemProperties &systemProperties)
 Initializes the application to a consistent state. More...
 
void initializeGL ()
 Initializes the graphics language subsystem. More...
 
bool loadKzbFile (string_view fileName, bool setStartupPrefab)
 Loads a kzb file or multiple kzb files listed in a configuration file. More...
 
void main (const SystemProperties &systemProperties)
 Application entry point. More...
 
void resumeGL ()
 Resumes the graphics language subsystem. More...
 
void setRenderingAreaOffset (Vector2 offset)
 Sets the translation that Kanzi uses as the arrange transformation of the default Screen node. More...
 
void setRootCompositionTarget (TextureSharedPtr compositionTarget)
 Sets the root composition target of the application. More...
 
void suspendGL ()
 Suspends the graphics language subsystem. More...
 
void uninitialize ()
 Uninitializes the application. More...
 
void uninitializeGL ()
 Uninitializes the graphics language subsystem. More...
 
 ~Application () override
 Destructs the application object. More...
 
State modifiers.
void pause ()
 Puts the application from the Running state to the Paused state. More...
 
void resume ()
 Resumes the application from the Paused state to the Running state. More...
 
void quit ()
 Quits the application. More...
 
Studio preview specific functions.
void patchProject (uintmax_t byteCount, const byte *bytes)
 Applies a Kanzi Studio Preview patch. More...
 
- Public Member Functions inherited from kanzi::Module
virtual void destroy ()
 
virtual MetaclassContainer getMetaclassesOverride ()
 
 Module ()
 
virtual void registerDebugRenderingFunctions (DebugRenderRegistry &)
 Register the module debug rendering functions. More...
 
virtual void registerMetadataOverride (ObjectFactory &)
 Register the rest of module metadata, such as loaders for types in module. More...
 
void setDomain (Domain *domain)
 Set the domain. More...
 

Protected Member Functions

Initialization functions.
virtual void initializeProperties (const SystemProperties &systemProperties)
 Loads the application properties, based on configuration file and command-line arguments. More...
 
virtual void initializeSystem ()
 Initializes profiling, event sources, and graphics output. More...
 
virtual void initializePlatform ()
 Initializes platform configuration. More...
 
virtual void uninitializePlatform ()
 Unitializes platform configuration. More...
 
virtual void initializeDomain ()
 Initializes Kanzi Domain and loads a kzb file. More...
 
virtual void initializeMainLoopTasks ()
 Attaches the default tasks to the main loop scheduler. More...
 
void applyMainLoopConfigs ()
 Applies the frame limit and idle-suspension configurations from the application properties to the main loop scheduler, and attaches event handles and preconditions. More...
 
void setFontBackendProperties ()
 Applies the font backend properties from the application properties to the FontManager. More...
 
Input stage functions.
void clearEventQueue ()
 Clears the event queue. More...
 
void gatherEvents ()
 Gathers all input events from the event sources into the event queue. More...
 
void handleApplicationEvents ()
 Executes the application-defined event handler on all events in the event queue. More...
 
virtual void handleEvents (EventQueue &eventQueue)
 Executes the application-defined event handler on all events in the event queue. More...
 
void handleGraphicsEvents ()
 Executes the event handler of the graphics subsystem. The events to handle are from the event queue. More...
 
void handleInputManagerEvents ()
 Executes the event handler of the input subsystem. The events to handle are from the event queue. More...
 
User stage functions.
void loadStartupKzb ()
 Instantiates and attaches the startup Screen node from the startup prefab. More...
 
void progressDeploymentQueue ()
 Processes the deployment queue for asynchronous loading tasks. More...
 
void updateRenderer (chrono::nanoseconds deltaTime)
 Advances renderer clock with time delta, and attaches active graphics output to it. More...
 
void measurePerformance (chrono::nanoseconds deltaTime)
 Updates the calculation of the Application frame rate. More...
 
Layout stage functions.
void adjustRenderingArea ()
 Sets the rendering area on the graphics output based on the size, orientation, and metrics. More...
 
void layout ()
 Lays out the node tree. More...
 
Animate stage functions.
void tickAnimations (chrono::nanoseconds deltaTime)
 Ticks all the active animations. More...
 
Render stage functions.
virtual void render ()
 Renders the node tree. More...
 
void renderPerformanceInfo ()
 Renders the Performance HUD. More...
 
void clearAllRenderBuffers (ColorRGBA clearColor)
 Clears all render buffers. More...
 
Present stage functions.
void present ()
 Updates the graphics output buffer with the rendered node tree. More...
 
Callbacks.
virtual void onStartup ()
 Callback for the startup logic. More...
 
virtual void onShutdown ()
 Callback for the shutdown logic. More...
 
virtual void onConfigure (ApplicationProperties &configuration)
 Callback for configuring the application properties. More...
 
virtual void onProjectLoaded ()
 Callback for initializations that use data from a kzb file. More...
 
virtual void onUpdate (chrono::nanoseconds deltaTime)
 Callback for the update logic. More...
 
virtual void onPointerInputEvent (const PointerEvent &pointerEvent)
 Callback for handling of input events from a pointing device, such as a mouse or touch screen. More...
 
virtual void onKeyInputEvent (const KeyEvent &keyEvent)
 Callback for handling input events from keyboard. More...
 
virtual optional< chrono::nanoseconds > onSuspend (chrono::nanoseconds remainingFrameAllotment)
 Callback for determining the duration of suspension in a main loop frame. More...
 
virtual void onPause ()
 Kanzi calls this callback when the application main loop enters the Paused state. More...
 
virtual void onResume ()
 Kanzi calls this callback when the application main loop returns from the Paused to the Running state. More...
 
virtual void onResumeCheck ()
 Kanzi calls this callback for the event handling logic when the application main loop is in the Paused state. More...
 
Overrides.
virtual void mainOverride (const SystemProperties &systemProperties)
 Override function for main(). More...
 
virtual void initializeOverride (const SystemProperties &systemProperties)
 Override function for initialize(). More...
 
virtual void uninitializeOverride ()
 Override function for uninitialize(). More...
 
virtual void initializeGLOverride ()
 Override function for initializeGL(). More...
 
virtual void uninitializeGLOverride ()
 Override function for uninitializeGL(). More...
 
virtual void suspendGLOverride ()
 Override function for suspendGL(). More...
 
virtual void resumeGLOverride ()
 Override function for resumeGL(). More...
 
virtual void progressDeploymentQueueOverride ()
 Override function for progressDeploymentQueue(). More...
 
virtual void setScreenOverride ()
 Override function for setScreen(). More...
 
- Protected Member Functions inherited from kanzi::Module
virtual ~Module ()=default
 Destructor. More...
 

Protected Attributes

ApplicationProperties m_applicationProperties
 Application properties. More...
 
KzuEnginem_engine
 Kanzi Engine instance. More...
 
MainLoopTaskToken m_loadStartupKzbToken
 The token of LoadStartyKzb Main Loop Scheduler task. More...
 
MainLoopScheduler m_mainLoopScheduler
 Main loop scheduler. More...
 
unique_ptr< PerformanceInfom_performanceInfo
 Performance HUD information. More...
 
bool m_projectLoaded
 Flag to be set when project has been loaded. More...
 
string m_startupPrefabUrl
 URL of the startup prefab. More...
 
SystemProperties m_systemProperties
 Container of command line parameters of the program. More...
 
- Protected Attributes inherited from kanzi::Module
Domainm_domain
 The domain this module is registered to. More...
 

Friends

class PreviewApplication
 

Accessors and mutators.

DomaingetDomain () const
 Access domain. More...
 
Renderer3DgetRenderer3D () const
 Access the renderer. More...
 
Node2DSharedPtr getRoot () const
 Access the root node. More...
 
ScreenSharedPtr getScreen () const
 Access the Screen node. More...
 
void setScreen (ScreenSharedPtr screen)
 Sets, configures, and attaches the Screen node of the Application. More...
 
const MainLoopSchedulergetMainLoopScheduler () const
 Access the associated MainLoopScheduler. More...
 
MainLoopSchedulergetMainLoopScheduler ()
 Access the associated MainLoopScheduler. More...
 
ResourceManagergetResourceManager () const
 Access resource manager. More...
 
KZ_DEPRECATED InputManagergetInputManager () const
 Access input manager. More...
 
detail::MessageDispatcher * getMessageDispatcher () const
 Access message dispatcher. More...
 
float getFramesPerSecond () const
 Gets the frame rate of the application. More...
 
size_t getGraphicsOutputCount () const
 Access graphics output count. More...
 
GraphicsOutputSharedPtr getGraphicsOutput (size_t index=0) const
 Access graphics outputs. More...
 
template<typename Interface >
shared_ptr< Interface > getGraphicsOutput (size_t index) const
 Query graphics output interfaces. More...
 
void appendGraphicsOutput (GraphicsOutputSharedPtr graphicsOutput)
 Attach graphics output. More...
 
void removeGraphicsOutput (size_t index=0)
 Remove graphics output. More...
 
size_t getEventSourceCount () const
 Access event source count. More...
 
EventSourceSharedPtr getEventSource (size_t index=0) const
 Access event sources. More...
 
void appendEventSource (EventSourceSharedPtr eventSource)
 Attach event source to domain and register its event handle with main loop scheduler. More...
 
void removeEventSource (size_t index=0)
 Remove event source. More...
 
MainLoopState getState () const
 Access application state. More...
 
ApplicationProperties getApplicationProperties () const
 Access application properties. More...
 
ApplicationProperties::PerformanceInfoLevel getPerformanceInfoLevel () const
 Gets the Performance HUD information level. More...
 
void setPerformanceInfoLevel (ApplicationProperties::PerformanceInfoLevel level)
 Sets the Performance HUD information level. More...
 
void loadFontEngine (ApplicationProperties::FontEngine fontEngine)
 Loads the font engine for the font manager. More...
 
void setAllowIndefiniteSleep (bool enabled)
 Sets or resets the flag that allows indefinite sleep. More...
 
void setDeploymentQueueTimeBudget (chrono::nanoseconds budget)
 Sets the time budget used to deploy asynchronously loaded Resources per frame. More...
 
void logStartupProfilingData () const
 Logs startup profiling data. More...
 
virtual bool isToolPresent () const
 Indicates whether application is running in the Kanzi Studio Preview. More...
 
void logGraphicsInformation ()
 Log graphics information based on application properties. More...
 
KZ_DEPRECATED KzuEnginegetEngine () const
 Access Kanzi Engine. More...
 
PerformanceInfoacquirePerformanceInfo ()
 Acquire performance information object. More...
 
void restoreNodeResources (Screen &screen)
 Restores node resources after application sleep by calling Node::restoreResources() recursively for the nodes in the tree. More...
 

Additional Inherited Members

- Public Types inherited from kanzi::Module
typedef vector< const Metaclass * > MetaclassContainer
 
typedef MetaclassContainer::iterator MetaclassIterator
 

Detailed Description

Application class is the base class for Kanzi applications.

It implements the Kanzi main loop with help of MainLoopScheduler.

You can customize your application by overriding the virtual functions of the Application class.

You can also customize the main loop using the MainLoopScheduler, which you can access with getMainLoopScheduler(). The MainLoopScheduler lets you add or modify the tasks and stages of the main loop. Kanzi adds the default main loop tasks to the respective stages inside initializeMainLoopTasks().

This diagram shows the overall application control flow. Green items are virtual functions. Gray items are main loop stages. Dotted items are main loop callbacks.

Constructor & Destructor Documentation

kanzi::Application::Application ( )
explicit

Constructs the application object.

kanzi::Application::~Application ( )
override

Destructs the application object.

Member Function Documentation

void kanzi::Application::initialize ( const SystemProperties systemProperties)

Initializes the application to a consistent state.

After constructing the application, this is the first function that the application framework calls. This function tries to read the file application.cfg. Do not call this function before the file system of the operating system has been initialized.

To change the default behavior, override initializeOverride().

Parameters
systemPropertiesCommand line parameters of the program.
void kanzi::Application::initializeGL ( )

Initializes the graphics language subsystem.

The application framework calls this function before entering the program main loop, but after the application framework activates a GL context. It initializes OpenGL-related subsystems.

To change the default behavior, override initializeGLOverride().

void kanzi::Application::resumeGL ( )

Resumes the graphics language subsystem.

If you call suspendGL() during suspension, the application framework calls this function during application resume. This function deploys GPU resources that were undeployed during suspendGL().

To change the default behavior, override resumeGLOverride().

void kanzi::Application::main ( const SystemProperties systemProperties)

Application entry point.

This high-level function implements the default initialization and the main loop. The application framework calls this function, except on callbacks-only systems.

To change the default behavior, override mainOverride().

Parameters
systemPropertiesCommand line parameters of the program.
void kanzi::Application::uninitialize ( )

Uninitializes the application.

This is the last function that the application framework calls before destruction.

To change the default behavior, override uninitializeOverride().

void kanzi::Application::uninitializeGL ( )

Uninitializes the graphics language subsystem.

The application framework calls this function after exiting the program main loop, but before it deactivates a GL context. It undeploys all GPU resources.

To change the default behavior, override uninitializeGLOverride().

void kanzi::Application::suspendGL ( )

Suspends the graphics language subsystem.

The application framework calls this function during application suspension, on systems where the graphics language resources are not guaranteed to be retained until the application resumes. It undeploys all GPU resources and reschedules them for redeployment.

When your applications suspends, the GPU resources not stored in a kzb file become invalid. Destroy these resources and recreate them on resume. Make sure that after recreating a resource the pointers are correct. Kanzi automatically restores all other resources.

To change the default behavior, override suspendGLOverride().

void kanzi::Application::pause ( )

Puts the application from the Running state to the Paused state.

void kanzi::Application::resume ( )

Resumes the application from the Paused state to the Running state.

void kanzi::Application::quit ( )

Quits the application.

Domain* kanzi::Application::getDomain ( ) const

Access domain.

Returns
Pointer to domain.
Renderer3D* kanzi::Application::getRenderer3D ( ) const

Access the renderer.

Returns
Renderer3D pointer.
Node2DSharedPtr kanzi::Application::getRoot ( ) const

Access the root node.

Returns
Node shared pointer.
ScreenSharedPtr kanzi::Application::getScreen ( ) const

Access the Screen node.

Returns
Screen shared pointer.
void kanzi::Application::setScreen ( ScreenSharedPtr  screen)

Sets, configures, and attaches the Screen node of the Application.

The default implementation associates the screen of the application with InputManager and FocusManager instances. You can configure the given screen in setScreenOverride().

If the Application already has a Screen node set, Kanzi detaches and releases that Screen, and sets the given screen node.

Kanzi calls this method automatically on loadStartupKzb().

See also
setScreenOverride()
Parameters
screenShared pointer to the Screen node to set.
const MainLoopScheduler& kanzi::Application::getMainLoopScheduler ( ) const

Access the associated MainLoopScheduler.

Returns
Pointer to the MainLoopScheduler instance.
MainLoopScheduler& kanzi::Application::getMainLoopScheduler ( )

Access the associated MainLoopScheduler.

Returns
Pointer to the MainLoopScheduler instance.
ResourceManager* kanzi::Application::getResourceManager ( ) const

Access resource manager.

Returns
Resource manager pointer.
KZ_DEPRECATED InputManager* kanzi::Application::getInputManager ( ) const

Access input manager.

Returns
Input manager pointer.
Deprecated:
In Kanzi 3.9.6. Use Screen::getInputManager() instead.
detail::MessageDispatcher* kanzi::Application::getMessageDispatcher ( ) const

Access message dispatcher.

Returns
Message dispatcher pointer.
float kanzi::Application::getFramesPerSecond ( ) const

Gets the frame rate of the application.

To make sure that this function returns the correct frame rate, the main loop scheduler task MeasurePerformance calls measurePerformance() once per frame by default.

If you override the user stage tasks of the main loop scheduler, including the MeasurePerformance task, call measurePerformance() manually every frame. This way you make sure that getFramesPerSecond() returns valid values.

Returns
The frame rate in frames per second.
See also
measurePerformance()
Since
Kanzi 3.9.6
size_t kanzi::Application::getGraphicsOutputCount ( ) const

Access graphics output count.

Returns
Number of attached graphics outputs.
GraphicsOutputSharedPtr kanzi::Application::getGraphicsOutput ( size_t  index = 0) const

Access graphics outputs.

Parameters
indexIndex of the graphics output to access.
Returns
Shared pointer to the specified graphics output.
template<typename Interface >
shared_ptr<Interface> kanzi::Application::getGraphicsOutput ( size_t  index) const
inline

Query graphics output interfaces.

Template Parameters
InterfaceInterface of the graphics output to query.
Parameters
indexIndex of the graphics output to query.
Returns
Shared pointer to the specified graphics output interface, or nullptr if the interface is not supported.
void kanzi::Application::appendGraphicsOutput ( GraphicsOutputSharedPtr  graphicsOutput)

Attach graphics output.

Parameters
graphicsOutputShared pointer to the graphics output to attach.
void kanzi::Application::removeGraphicsOutput ( size_t  index = 0)

Remove graphics output.

Parameters
indexIndex of the graphics output to remove.
size_t kanzi::Application::getEventSourceCount ( ) const

Access event source count.

Returns
Number of attached event sources.
EventSourceSharedPtr kanzi::Application::getEventSource ( size_t  index = 0) const

Access event sources.

Parameters
indexIndex of the event source to access.
Returns
Shared pointer to the specified event source.
void kanzi::Application::appendEventSource ( EventSourceSharedPtr  eventSource)

Attach event source to domain and register its event handle with main loop scheduler.

To attach event source to domain without registering event handle, use Domain::appendEventSource(). To register event handle with main loop scheduler without attaching to domain, use MainLoopScheduler::setInputEventHandle().

Parameters
eventSourceShared pointer to the event source to attach.
void kanzi::Application::removeEventSource ( size_t  index = 0)

Remove event source.

Parameters
indexIndex of the event source to remove.
MainLoopState kanzi::Application::getState ( ) const

Access application state.

Returns
Current application state.
ApplicationProperties kanzi::Application::getApplicationProperties ( ) const

Access application properties.

Returns
Current application properties.
ApplicationProperties::PerformanceInfoLevel kanzi::Application::getPerformanceInfoLevel ( ) const
inline

Gets the Performance HUD information level.

If the Performance HUD information level is not ApplicationProperties::PerformanceInfoLevelDisabled, Kanzi draws the Performance HUD after calling onPostRender().

Returns
Returns the Performance HUD information level.
void kanzi::Application::setPerformanceInfoLevel ( ApplicationProperties::PerformanceInfoLevel  level)
inline

Sets the Performance HUD information level.

This is equal to the application configuration ApplicationProperties::PerformanceInfoLevel option.

Parameters
level- To turn off the Performance HUD, use ApplicationProperties::PerformanceInfoLevelDisabled (0). The default value.
void kanzi::Application::loadFontEngine ( ApplicationProperties::FontEngine  fontEngine)

Loads the font engine for the font manager.

Parameters
fontEngineThe font engine that the font manager uses.
void kanzi::Application::setAllowIndefiniteSleep ( bool  enabled)
inline

Sets or resets the flag that allows indefinite sleep.

Parameters
enabled- To enable indefinite sleep, set to true.
  • To always wake up in frame time, set to false.
void kanzi::Application::setDeploymentQueueTimeBudget ( chrono::nanoseconds  budget)
inline

Sets the time budget used to deploy asynchronously loaded Resources per frame.

This does not guarantee that the work will be completed within the budget, just that no new items will be started after the budget has expired. At a minimum, one item will be processed each frame if it exists.

Parameters
budgetAmount of time to spend processing Deployment Queue items per frame.
void kanzi::Application::patchProject ( uintmax_t  byteCount,
const byte bytes 
)

Applies a Kanzi Studio Preview patch.

Kanzi Studio Preview uses this function internally.

Parameters
byteCountSize of kzb file.
bytesPointer to the contents of the kzb file.
StartupProfilerRegistry& kanzi::Application::getStartupProfilerRegistry ( ) const
inline

Gets the startup profiler registry.

Returns
The reference to the startup profiler registry.
bool kanzi::Application::loadKzbFile ( string_view  fileName,
bool  setStartupPrefab 
)

Loads a kzb file or multiple kzb files listed in a configuration file.

Parameters
fileNameName of the kzb file to load or the name of the configuration file from which to read the names of kzb files to load.
setStartupPrefabWhether to set the startup prefab of the loaded kzb file as the startup prefab of the application. When loading multiple kzb files, Kanzi uses the startup prefab from the kzb file it loads last.
Returns
If loading the kzb file or files succeeded, true, otherwise false.
Since
Kanzi 3.9.6
void kanzi::Application::setRenderingAreaOffset ( Vector2  offset)

Sets the translation that Kanzi uses as the arrange transformation of the default Screen node.

Parameters
offsetThe translation that Kanzi uses as the arrange transformation of the default Screen node.
Since
Kanzi 3.9.6
Vector2 kanzi::Application::getRenderingAreaOffset ( ) const

Returns the translation that Kanzi uses as the arrange transformation of the default Screen node.

Returns
The translation that Kanzi uses as the arrange transformation of the default Screen node.
Since
Kanzi 3.9.6
void kanzi::Application::setRootCompositionTarget ( TextureSharedPtr  compositionTarget)

Sets the root composition target of the application.

Parameters
compositionTargetThe composition target texture to use.
Since
Kanzi 3.9.6
TextureSharedPtr kanzi::Application::getRootCompositionTarget ( ) const

Returns the root composition target of the application.

Returns
The root composition target of the application. If the application does not have a root composition target, returns an empty pointer.
Since
Kanzi 3.9.6
virtual void kanzi::Application::initializeProperties ( const SystemProperties systemProperties)
protectedvirtual

Loads the application properties, based on configuration file and command-line arguments.

Parameters
systemPropertiesCommand line parameters of the program.
virtual void kanzi::Application::initializeSystem ( )
protectedvirtual

Initializes profiling, event sources, and graphics output.

virtual void kanzi::Application::initializePlatform ( )
protectedvirtual

Initializes platform configuration.

virtual void kanzi::Application::uninitializePlatform ( )
protectedvirtual

Unitializes platform configuration.

virtual void kanzi::Application::initializeDomain ( )
protectedvirtual

Initializes Kanzi Domain and loads a kzb file.

virtual void kanzi::Application::initializeMainLoopTasks ( )
inlineprotectedvirtual

Attaches the default tasks to the main loop scheduler.

void kanzi::Application::applyMainLoopConfigs ( )
protected

Applies the frame limit and idle-suspension configurations from the application properties to the main loop scheduler, and attaches event handles and preconditions.

void kanzi::Application::setFontBackendProperties ( )
protected

Applies the font backend properties from the application properties to the FontManager.

Since
Kanzi 3.9.4
void kanzi::Application::clearEventQueue ( )
protected

Clears the event queue.

void kanzi::Application::gatherEvents ( )
protected

Gathers all input events from the event sources into the event queue.

void kanzi::Application::handleApplicationEvents ( )
protected

Executes the application-defined event handler on all events in the event queue.

See Application::handleEvents.

virtual void kanzi::Application::handleEvents ( EventQueue eventQueue)
protectedvirtual

Executes the application-defined event handler on all events in the event queue.

Parameters
eventQueueReference to the event queue for user input and window events.
void kanzi::Application::handleGraphicsEvents ( )
protected

Executes the event handler of the graphics subsystem. The events to handle are from the event queue.

void kanzi::Application::handleInputManagerEvents ( )
protected

Executes the event handler of the input subsystem. The events to handle are from the event queue.

void kanzi::Application::loadStartupKzb ( )
protected

Instantiates and attaches the startup Screen node from the startup prefab.

If a startup kzb file is not set, or the startup Screen node is not set, creates the default Screen node. Kanzi calls this function automatically at application startup.

void kanzi::Application::progressDeploymentQueue ( )
protected

Processes the deployment queue for asynchronous loading tasks.

By default this function processes every frame a single item from the deployment queue of background loading tasks.

To change the default behavior, override progressDeploymentQueueOverride().

void kanzi::Application::updateRenderer ( chrono::nanoseconds  deltaTime)
protected

Advances renderer clock with time delta, and attaches active graphics output to it.

Parameters
deltaTimeTime in nanoseconds elapsed since the previous frame.
void kanzi::Application::measurePerformance ( chrono::nanoseconds  deltaTime)
protected

Updates the calculation of the Application frame rate.

To calculate the frame rate correctly, Kanzi must call this function once per frame. The default main loop scheduler task MeasurePerformance does this.

Parameters
deltaTimeTime in nanoseconds elapsed between the start of the previous frame and the start of the current frame.
void kanzi::Application::adjustRenderingArea ( )
protected

Sets the rendering area on the graphics output based on the size, orientation, and metrics.

void kanzi::Application::layout ( )
protected

Lays out the node tree.

void kanzi::Application::tickAnimations ( chrono::nanoseconds  deltaTime)
protected

Ticks all the active animations.

Parameters
deltaTimeTime in nanoseconds since the previous frame.
virtual void kanzi::Application::render ( )
protectedvirtual

Renders the node tree.

void kanzi::Application::renderPerformanceInfo ( )
protected

Renders the Performance HUD.

void kanzi::Application::clearAllRenderBuffers ( ColorRGBA  clearColor)
protected

Clears all render buffers.

void kanzi::Application::present ( )
protected

Updates the graphics output buffer with the rendered node tree.

virtual void kanzi::Application::onStartup ( )
protectedvirtual

Callback for the startup logic.

Kanzi calls this function immediately after the application initialization.

virtual void kanzi::Application::onShutdown ( )
protectedvirtual

Callback for the shutdown logic.

Kanzi calls this function immediately before the application un-initialization.

virtual void kanzi::Application::onConfigure ( ApplicationProperties configuration)
protectedvirtual

Callback for configuring the application properties.

Kanzi calls this callback before it reads the application.cfg and before it initializes the graphics subsystem.

Parameters
configurationAllows modification of the application properties.
See also
ApplicationProperties, NativeWindowProperties, KzsSurfaceProperties, EventSourceProperties, PerformanceInfoProperties, ApplicationProperties::FontEngine

Reimplemented in kanzi::ExampleApplication.

virtual void kanzi::Application::onProjectLoaded ( )
protectedvirtual

Callback for initializations that use data from a kzb file.

Kanzi calls this function right after it loads a kzb file.

virtual void kanzi::Application::onUpdate ( chrono::nanoseconds  deltaTime)
protectedvirtual

Callback for the update logic.

Kanzi calls this function every frame in the User stage of the main loop.

Parameters
deltaTimeTime in nanoseconds elapsed since the previous frame.
Deprecated:
In Kanzi 3.9. Insert a task into MainLoopScheduler UserStage instead.
virtual void kanzi::Application::onPointerInputEvent ( const PointerEvent pointerEvent)
protectedvirtual

Callback for handling of input events from a pointing device, such as a mouse or touch screen.

Kanzi calls this function inside the Input stage of the main loop.

Parameters
pointerEventReference to the event.
virtual void kanzi::Application::onKeyInputEvent ( const KeyEvent keyEvent)
protectedvirtual

Callback for handling input events from keyboard.

Kanzi calls this function inside the Input stage of the main loop.

Parameters
keyEventReference to the event.

Reimplemented in kanzi::ExampleApplication.

virtual optional<chrono::nanoseconds> kanzi::Application::onSuspend ( chrono::nanoseconds  remainingFrameAllotment)
protectedvirtual

Callback for determining the duration of suspension in a main loop frame.

Kanzi calls this function when the main loop decides to enter suspension.

Parameters
remainingFrameAllotmentTime remaining in the current frame based on the configured frame limit and time elapsed since its start.
Returns
Default implementation calculates appropriate timeout based on active animations, timers, and resources waiting for deployment. An override must choose between one of these returns:
  • Return nullopt for an indefinite suspend.
  • Return a different definite timeout length in chrono::nanoseconds().
  • Return 0 (chrono::nanoseconds) to cancel the suspend.
virtual void kanzi::Application::onPause ( )
protectedvirtual

Kanzi calls this callback when the application main loop enters the Paused state.

virtual void kanzi::Application::onResume ( )
protectedvirtual

Kanzi calls this callback when the application main loop returns from the Paused to the Running state.

virtual void kanzi::Application::onResumeCheck ( )
protectedvirtual

Kanzi calls this callback for the event handling logic when the application main loop is in the Paused state.

virtual void kanzi::Application::mainOverride ( const SystemProperties systemProperties)
protectedvirtual

Override function for main().

Parameters
systemPropertiesCommand line parameters of the program.
virtual void kanzi::Application::initializeOverride ( const SystemProperties systemProperties)
protectedvirtual

Override function for initialize().

Parameters
systemPropertiesCommand line parameters of the program.
virtual void kanzi::Application::uninitializeOverride ( )
protectedvirtual

Override function for uninitialize().

virtual void kanzi::Application::initializeGLOverride ( )
protectedvirtual

Override function for initializeGL().

virtual void kanzi::Application::uninitializeGLOverride ( )
protectedvirtual

Override function for uninitializeGL().

virtual void kanzi::Application::suspendGLOverride ( )
protectedvirtual

Override function for suspendGL().

virtual void kanzi::Application::resumeGLOverride ( )
protectedvirtual

Override function for resumeGL().

virtual void kanzi::Application::progressDeploymentQueueOverride ( )
protectedvirtual

Override function for progressDeploymentQueue().

virtual void kanzi::Application::setScreenOverride ( )
protectedvirtual

Override function for setScreen().

The default implementation associates the screen of the application with InputManager and FocusManager instances. To disable input and focus management on the application screen, override this method to clear the input and focus managers from the application screen.

See also
Screen::setInputManager(), Screen::setFocusManager()
void kanzi::Application::logStartupProfilingData ( ) const
protected

Logs startup profiling data.

virtual bool kanzi::Application::isToolPresent ( ) const
inlineprotectedvirtual

Indicates whether application is running in the Kanzi Studio Preview.

Returns
If the application is running in the Kanzi Studio Preview, returns true, otherwise false.
void kanzi::Application::logGraphicsInformation ( )
protected

Log graphics information based on application properties.

KZ_DEPRECATED KzuEngine* kanzi::Application::getEngine ( ) const
protected

Access Kanzi Engine.

Returns
Returns an instance of Kanzi Engine.
Deprecated:
In Kanzi 3.9.6. Use the functionality provided by the Application, Screen, and ResourceManager classes.
PerformanceInfo& kanzi::Application::acquirePerformanceInfo ( )
protected

Acquire performance information object.

If performance information object does not exist, this function creates it.

void kanzi::Application::restoreNodeResources ( Screen screen)
protected

Restores node resources after application sleep by calling Node::restoreResources() recursively for the nodes in the tree.

Parameters
screenThe Screen of the node tree for which to restore resources.
See also
Node::restoreResources()
Since
Kanzi 3.9.6

Friends And Related Function Documentation

friend class PreviewApplication
friend

Member Data Documentation

SystemProperties kanzi::Application::m_systemProperties
protected

Container of command line parameters of the program.

ApplicationProperties kanzi::Application::m_applicationProperties
protected

Application properties.

KzuEngine* kanzi::Application::m_engine
mutableprotected

Kanzi Engine instance.

Deprecated:
In Kanzi 3.9.6. Use the functionality provided by the Application, Screen, and ResourceManager classes.
unique_ptr<PerformanceInfo> kanzi::Application::m_performanceInfo
protected

Performance HUD information.

bool kanzi::Application::m_projectLoaded
protected

Flag to be set when project has been loaded.

MainLoopScheduler kanzi::Application::m_mainLoopScheduler
protected

Main loop scheduler.

MainLoopTaskToken kanzi::Application::m_loadStartupKzbToken
protected

The token of LoadStartyKzb Main Loop Scheduler task.

string kanzi::Application::m_startupPrefabUrl
protected

URL of the startup prefab.


The documentation for this class was generated from the following file: